﻿<!DOCTYPE HTML>
<html lang="zh">
<head>
<title>Array 对象 - 方法 &amp; 属性 | AutoHotkey v2</title>
<meta name="description" content="An Array object contains a list or sequence of values." />
<meta name="ahk:equiv-v1" content="objects/Object.htm" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
<script type="text/javascript">$(function(){0<=window.navigator.userAgent.toLowerCase().indexOf("ucbrowser")&&CaoNiMaDeUc()})</script>
</head>
<body>

<h1>Array 对象</h1>
<pre class="NoIndent">class Array extends Object</pre>

<p><strong>Array(数组)</strong> 对象包含值的列表或序列.</p>
<p>值由它们在数组中的位置(称为 <em>数组索引</em>) 来表示, 其中位置 1 是第一个元素.</p>
<p>数组通常是通过将值的列表括在方括号中来创建的. 例如:</p>
<pre>veg := ["Asparagus", "Broccoli", "Cucumber"]
Loop veg.Length
    MsgBox veg[A_Index]</pre>
<p>负索引可用于反向处理元素, 因此 -1 是最后一个元素, -2 是倒数第二个元素, 依此类推.</p>
<p>尝试使用超出范围的数组索引(例如零, 或者其绝对值大于数组的 <a href="#Length">Length</a>) 被视为错误, 并将导致抛出 <a href="Error.htm#IndexError">IndexError</a>. 向数组添加新元素的最佳方法是调用 <a href="#InsertAt">InsertAt</a> 或 <a href="#Push">Push</a>. 例如:</p>
<pre>users := Array()
users.Push A_UserName
MsgBox users[1]</pre>
<p>也可以通过为 <a href="#Length">Length</a> 指定更大的值来扩展数组. 这些索引是有效的, 但是 <a href="#Has">Has</a> 将显示新元素没有值. 元素没有值通常用于<a href="../Functions.htm#VariadicCall">可变参数调用</a>或<a href="../Functions.htm#Variadic">可变参数函数</a>, 但也可以被用于任何目的.</p>
<p>下面使用 "ArrayObj" 作为任何数组对象的占位符, 因为 "Array" 就是类本身.</p>
<p>除了从 <a href="Object.htm">Object</a> 继承的方法和属性外, Array 对象还具有以下预定义的方法和属性:</p>
<p><strong>静态方法:</strong></p>
<ul>
  <li><a href="#Call">Call</a></li>
</ul>
<p><strong>方法:</strong></p>
<ul>
  <li><a href="#Clone">Clone</a></li>
  <li><a href="#Delete">Delete</a></li>
  <li><a href="#Has">Has</a></li>
  <li><a href="#InsertAt">InsertAt</a></li>
  <li><a href="#Pop">Pop</a></li>
  <li><a href="#Push">Push</a></li>
  <li><a href="#RemoveAt">RemoveAt</a></li>
  <li><a href="#__Enum">__Enum</a></li>
  <li><a href="#__New">__New</a></li>
</ul>
<p><strong>属性:</strong></p>
<ul>
  <li><a href="#Length">Length</a></li>
  <li><a href="#Capacity">Capacity</a></li>
  <li><a href="#__Item">__Item</a></li>
</ul>

<h2 id="StaticMethods">静态方法</h2>

<div class="methodShort" id="Call"><h2>Call</h2>
<p>创建一个包含指定值的新数组.</p>
<pre class="Syntax">ArrayObj := <span class="func">Array</span>(<span class="optional">Value, Value2, ..., Value<i>N</i></span>)</pre>
<p>参数由 <a href="#__New">__New</a> 定义.</p>
</div>

<h2 id="Methods">方法</h2>

<div class="methodShort" id="Clone"><h2>Clone</h2>
<p>返回对象的一个浅拷贝.</p>
<pre class="Syntax">Clone := ArrayObj.<span class="func">Clone</span>()</pre>
<p>所有数组元素都被复制到新数组. 对象 <em>引用</em> 被复制(就像普通的赋值一样), 而不是对象本身.</p>
<p>根据 <a href="Object.htm#Clone">Obj.Clone</a> 来复制自有的属性, 方法和基.</p>
</div>

<div class="methodShort" id="Delete"><h2>Delete</h2>
<p>删除数组元素的值, 使索引不包含值.</p>
<pre class="Syntax">ArrayObj.<span class="func">Delete</span>(Index)</pre>
<dl>
  <dt>Index</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>一个有效的数组索引.</p>
  </dd>
  <dt>返回值</dt>
  <dd><p>删除的值(如果没有, 则为空).</p></dd>
</dl>
<p>Delete 不影响数组的 <a href="#Length">Length(长度)</a>.</p>
<p>如果 <em>Index</em> 超出范围, 则抛出 <a href="Error.htm#ValueError">ValueError</a>.</p>
</div>

<div class="methodShort" id="Has"><h2>Has</h2>
<p>如果 <i>Index</i> 有效且在该位置有一个值, 则返回 true, 否则返回 false.</p>
<pre class="Syntax">ArrayObj.<span class="func">Has</span>(Index)</pre>
</div>

<div class="methodShort" id="InsertAt"><h2>InsertAt</h2>
<p>插入一个或多个值到给定位置.</p>
<pre class="Syntax">ArrayObj.<span class="func">InsertAt</span>(Index, Value1 <span class="optional">, Value2, ... Value<i>N</i></span>)</pre>
<dl>
  <dt>Index</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>插入 <em>Value1</em> 的位置. 随后的值插入到 Index+1, Index+2, 以此类推. 指定 0 为索引等同于指定 <a href="#Length">Length</a> + 1.</p>
  </dd>
  <dt>Value1 ...</dt>
  <dd>
    <p>要插入的一个或多个值. 要插入数组值, 请将 <code><a href="../Functions.htm#VariadicCall">theArray*</a></code> 作为最后一个参数传递.</p>
  </dd>
</dl>
<h3 id="InsertAt_Remarks">备注</h3>
<p>InsertAt 对应 <a href="#RemoveAt">RemoveAt</a>.</p>
<p>先前位于 <em>Index</em> 的项目或 <em>Index</em> 右侧的所有项目都移到右侧. 缺失的参数也会被插入, 但没有值. 例如:</p>
<pre>x := []
x.InsertAt(1, "A", "B") <em>; =&gt;  ["A", "B"]</em>
x.InsertAt(2, "C")      <em>; =&gt;  ["A", "C", "B"]</em>

<em>; 缺失的元素将保留:</em>
x := ["A", , "C"]
x.InsertAt(2, "B")      <em>; =&gt;  ["A", "B",    , "C"]</em>

x := ["C"]
x.InsertAt(1, , "B")    <em>; =&gt;  [   , "B", "C"]</em></pre>
<p>如果 <em>Index</em> 小于 <code>-ArrayObj.Length</code> 或大于 <code>ArrayObj.Length + 1</code>, 则抛出 <a href="Error.htm#ValueError">ValueError</a>. 例如, 对于一个包含 3 个项目的数组, <em>Index</em> 必须介于-3 和 4 之间(包含).</p>
</div>

<div class="methodShort" id="Pop"><h2>Pop</h2>
<p>删除并返回最后的数组元素.</p>
<pre class="Syntax">Value := ArrayObj.<span class="func">Pop</span>()</pre>
<p>下面这些都是等同的:</p>
<pre>Value := ArrayObj.Pop()
Value := ArrayObj.RemoveAt(ArrayObj.Length)
Value := ArrayObj.RemoveAt(-1)</pre>
<p>如果数组为空(<a href="#Length">Length</a> 为 0), 则抛出 <a href="Error.htm">Error</a>.</p>
</div>

<div class="methodShort" id="Push"><h2>Push</h2>
<p>追加值到数组的末尾.</p>
<pre class="Syntax">ArrayObj.<span class="func">Push</span>(<span class="optional">Value, Value2, ..., Value<i>N</i></span>)</pre>
<dl>
  <dt>Value ...</dt>
  <dd><p>要插入一个或多个值. 要插入数组值, 请将 <code><a href="../Functions.htm#VariadicCall">theArray*</a></code> 作为最后一个参数传递.</p></dd>
</dl>
</div>

<div class="methodShort" id="RemoveAt"><h2>RemoveAt</h2>
<p>从数组中移除项目.</p>
<pre class="Syntax">ArrayObj.<span class="func">RemoveAt</span>(Index <span class="optional">, Length</span>)</pre>
<dl>
  <dt>Index</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>要删除的值的索引.</p>
  </dd>
  
  <dt>Length</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>要删除的值的范围的长度. 如果省略, 则删除一项.</p>
  </dd>
  
  <dt>返回值</dt>
  <dd><p>如果省略 <em>Length</em>, 返回删除的值(如果没有则返回空值). 否则就没有返回值.</p></dd>
</dl>
<h3 id="RemoveAt_Remarks">备注</h3>
<p>RemoveAt 对应 <a href="#InsertAt">InsertAt</a>.</p>
<p>如果 <em>Index</em> 和 <em>Length</em> 所表示的范围不完全在数组的当前范围内, 则抛出 <a href="Error.htm#ValueError">ValueError</a>.</p>
<p><em>Pos</em> 侧的其余项将根据 <em>Length</em> 向左移动(如果省略则为 1). 例如:</p>
<pre>x := ["A", "B"]
MsgBox x.RemoveAt(1)  <em>; A</em>
MsgBox x[1]           <em>; B</em>

x := ["A", , "C"]
MsgBox x.RemoveAt(1, 2)  <em>; 空值</em>
MsgBox x[1]              <em>; C</em></pre>
</div>

<div class="methodShort" id="__New"><h2>__New</h2>
<p>追加项目. 等同于 <a href="#Push">Push</a>.</p>
<pre class="Syntax">ArrayObj.<span class="func">__New</span>(<span class="optional">Value, Value2, ..., Value<i>N</i></span>)</pre>
<p>这个方法是为了支持 <a href="#Call">Call</a> 而存在的, 并不打算直接调用. 请参阅<a href="../Objects.htm#Custom_NewDelete">构造和销毁</a>.</p>
</div>

<div class="methodShort" id="__Enum"><h2>__Enum</h2>
<p>枚举数组元素.</p>
<pre class="Syntax">For Value in ArrayObj</pre>
<pre class="Syntax">For Index, Value in ArrayObj</pre>
<p>返回一个新的<a href="Enumerator.htm">枚举器</a>. 该方法通常不直接调用. 而是将数组对象被直接传递给 <a href="../commands/For.htm">for-loop</a>, 其调用一次 __Enum 然后循环的每次迭代都调用一次枚举器. 每次对枚举器的调用都会返回下一个数组元素. for-loop 的变量对应于枚举器的参数, 它们是:</p>
<dl>
  <dt>Index</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>数组索引, 通常与 <a href="../Variables.htm#Index">A_Index</a> 相同. 其仅在两参数模式下存在.</p>
  </dd>
  <dt>Value</dt>
  <dd>
    <p>值(如果没有则为空).</p>
  </dd>
</dl>
</div>

<h2 id="Properties">属性</h2>

<div class="methodShort" id="Length"><h2>Length</h2>
<p>检索或设置数组的长度.</p>
<pre class="Syntax">Length := ArrayObj.<span class="func">Length</span></pre>
<pre class="Syntax">ArrayObj.<span class="func">Length</span> := Length</pre>
<p>长度包含没有值的元素. 因增加长度而产生的索引是有效的, 但是新元素没有值(由 <a href="#Has">Has</a> 反映出来).</p>
<pre>
MsgBox ["A", "B", "C"].Length  <em>;  3</em>
MsgBox ["A",    , "C"].Length  <em>;  3</em>
</pre>
</div>

<div class="methodShort" id="Capacity"><h2>Capacity</h2>
<p>检索或设置数组的当前容量.</p>
<pre class="Syntax">ArrayObj.<span class="func">Capacity</span> := MaxItems</pre>
<pre class="Syntax">MaxItems := ArrayObj.<span class="func">Capacity</span></pre>
<dl>
	<dt>MaxItems</dt>
	<dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>在必须自动扩展前, 数组可以包含最大元素数量. 如果设置的值小于 <a href="#Length">Length</a>, 则删除多的元素.</p>
  </dd>
</dl>
<pre>
x := ["A", "B", "C"]
x.push("D")
MsgBox  x.Capacity  <em>;  6</em>
</pre>

<pre>
x := ["A", "B", "C"]
x.push("D", "E", "F", "G")
MsgBox  x.Capacity  <em>;  7</em>
</pre>
</div>

<div class="methodShort" id="__Item"><h2>__Item</h2>
<p>检索或设置数组元素的值.</p>
<pre class="Syntax">Value := ArrayObj[Index]</pre>
<pre class="Syntax">ArrayObj[Index] := Value</pre>
<dl>
  <dt>Index</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>一个有效的数组索引; 也就是说, 一个绝对值在 1 和 <a href="#Length">Length</a>(包括) 之间的整数.</p>
    <p>负索引可用于反向处理元素, 因此 -1 是最后一个元素, -2 是倒数第二个元素, 依此类推.</p>
    <p>尝试使用超出范围的数组索引(例如零, 或者其绝对值大于数组的 <a href="#Length">Length(长度)</a>) 被视为错误, 并将导致抛出 <a href="Error.htm#IndexError">IndexError</a>.</p>
  </dd>
</dl>
<p>如上所示, 属性名 __Item 通常被省略, 但在覆盖属性时使用.</p>
</div>

</body>
</html>